Eddie
-----
MPW-inspired editor by Pavel Cisler
Based on Styled Text Engine by Hiroshi Lockheimer, a very cool piece of code


(c) 1997, 1998 Pavel Cisler
Send suggestions/feedback/bug reports to pavel@be.com. Current version of
Eddie is free. However if you use Eddie, you are morally obliged to send
me email describing your experience, complaining about annoyances, suggesting
features, reporting bugs, etc.

Note that both this document and the features of Eddie are in great flux.
Plugin API enabling plugin development is provided in the header
file Plugin.h. Plugin sample code will follow soon.

Before using Eddie, read the disclaimers at the end of this document.

See the enclosed ReleaseNotes for a list of the most recent features/fixes.

Main features
-------------
Extensive superset of MPW/BeIDE-like keyboard shortcuts, fully customizable,
	full featured responsive text engine.
Optional multiple keymaps, optional Emacs keyboard emulation.
Bash shell with worksheet support, fast shell input/output, tab completion,
	works great with makefiles.
Multiple undo levels.
Extended clipboard capability.
Windows with multiple panes.
Plugin architecture, allowing plugins access to undo, preference panels,
	keyboard shortcuts and more.
QuickFind window for fast incremental searching.
C++ prototyper, function popup, syntax highliting.


------------------------------------------------------------------------------------

Keyboard shortcuts
------------------

Note all keyboard shortcuts described in the following list apply to the default
MPW_like keyboard layout that comes with Eddie. The keyboard layout can be modified
in the UserStartup file and the shortcuts may be different on your setup. See
description of SetKey for a way of displaying all your current keyboard shortcuts.

Further note that some of the modifier keys used in the following description apply
to a Mac keyboard. If you have a Window keyboard, please do the following mental
transformation:

	Mac					Windows
	---------------------------
	Cmd (Command)	-	Alt
	Opt (Option)	-	Windows (or right Control on older keyboards)


Cmd-Tab		- open .h for .c, .cpp, open .c, .cpp for .h
Cmd-D		- open selection as file; selection is first expanded to include 
			  anything inside quotes, <> braces or spaces; works also if you 
			  just place the cursor anywhere in a file name or a path and makes
			  for a very convenient way of opening files. Further, if a file name
			  is followed by a line number in the format ~/foo/bar/bla.c:13 (a
			  result of running grep with the -n option), you may place the cursor
			  anywhere in the string, the file will be opened and the corresponding
			  line will be selected
Cmd-Opt-D	- open selection; same as above except it it does not attempt to 
			  expand the selection first; you have to select the whole file path.
			  If no text selected, an open header dialog is displayed. You may
			  enter a header file name, Eddie will search for it in the header
			  directories.

Cmd-B		- balance - select text inside <, (, {, [, ], }, ), > pair, 
			  including the brackets; press multiple times to expand to outer 
			  levels;

Cmd-Z		- Undo; use repeatedly for multiple undo levels
Cmd-Opt-Z	- Redo; use repeatedly for multiple redo levels

Cmd-left arrow		- skip to line beginning
Cmd-right arrow		- skip to line end
Opt-left arrow		- skip to word beginning
Opt-right arrow		- skip to word end
Control-right arrow	- skip to subword beginning
Control-left arrow	- skip to subword beginning
(subwords are parts of a word; subwords are delimited by underscores, digits,
changes from lower to upper case)

Cmd-up arrow		- scroll/move the selection to the top of the file 
Cmd-down arrow		- scroll/move the selection to the end of the file 
Option-up arrow		- scroll/move the selection one page up 
Option-down arrow	- scroll/move the selection one page down 

If shift key is held down in combination with any of the above cursor positioning
shortcuts the current selection will be extended apropriately.

Cmd-F			- open find window
Cmd-Option-F	- open QuickFind window, start searching from document top
Cmd-Control-F	- open QuickFind window, start searching from current position
Cmd-E			- enter selection as find string
Cmd-G			- find again
Cmd-Shift-G		- find again reverse
Cmd-H			- enter selection as find string and find
Cmd-Shift-H		- enter selection as find string and find reverse

Cmd-L			- open Go To Line dialog

Cmd-0			- open Worksheet (brings Worksheet to front if already open)
Cmd-<1-9>		- bring first 9 documents to front by number
Cmd-Opt-P		- rotate to next document
Cmd-Opt-Shift-P	- rotate to previous document

Cmd-Opt-S		- save all
Cmd-Opt-W		- close all (leave Worksheet open)

Control-Command-UpArrow 	- drag selected lines one line up
Control-Command-DownArrow	- drag selected lines one line down
Control-Command-LeftArrow	- drag selected characters one character left
Control-Command-RightArrow	- drag selected characters one character right


Mouse clicking
--------------

Double-click	- select word
Triple-click	- select line

Double-click any of <, (, {, [, ", ', ], }, ), >
		- select text contained inside the bracket pair
		  unlike Balance, the brackets themselves are not selected

Note on double clicking single/double quotes:
	The syntax coloring plugin is used to correctly determine quoted string
	starts and ends. If syntax coloring is turned off in a document, the
	double-clicked quote is treated as if it was the string-opening quote.

Control-double-click
		- select a subword

Cmd-double-click a line with an #if, #ifdef, #else, #endif
		- select text enclosed in an #ifdef block (this feature is part
	 	  of the IfdefBalancer plugin, see IfdefBalancer description for
	  	  more commands)

Double-click & drag	- select words
Triple-click & drag	- select lines
Control-double-click & drag - select subwords

Right mouse button click & drag a selection
(Cmd-Ctrl-mouse click & drag for single-button mice)
		- initiate a drag&drop

Note that drag&drop is intentionaly not initiated by just clicking and dragging
a selected text; My personal preference is to be able to double click and drag
to expand an existing selection at the cost of making drag initiation a tiny bit
harder. Hope this works for others too.

Middle mouse button click & drag
(Option-Ctrl-mouse click & drag for single button mice)
		- grab/scroll page

Option key-Middle mouse button click & drag
		- grab/scroll page faster

When grabbing and scrolling a page you may press or let go of the Option key
at any time to switch between the slow and faster scroll mode. You will notice
that the mouse cursor changes between a grabber hand and a grabber hand with a
go-faster-thunderbolt.

Status bar click			- open Go To Line dialog
Status bar press			- display document info
Dirty/ReadOnly icon click 	- open Execute Command dialog (see separate chapter)
Shell icon click 			- toggle between shell and text only modes

Pane splitting
--------------

Each window can be split into multiple panes. Each pane provides an indepenent view
of a given document and provides a handy way of working on two parts of the same
document simultaneously. Each pane can be scrolled independently to show a different
part of a document. The pane with current focus is shown with a solid selection
or cursor if the selection is empty.

Click and drag the narrow pane splitting thumb to split current window pane into
two. Each pane has two pane splitting thumbs, one right above the vertical scroll
bar (used to split a pane horizontaly), one left from the horizontal scroll bar
(used to split a pane verticaly). Double click the splitting thumb to split a pane
in half. Each new split pane contains a pane resizing thumb resembling the window
size box that can be used to resize a pane horizontaly or verticaly. Double clicking
this thumb will get rid of a pane. Dragging the resize thumb past the left or top
pane boundary will get rid of the pane. When resizing a window to make it smaller
panes that become too small get removed.

Keyboard and mouse navigation tips
----------------------------------
Not all text navigation functions are bound to keyboard shortcut in the default
Eddie setup due to a large number of these functions. Check out the Primitives
function to list all the available navigation functions and edit the UserStartup
document to set up Eddie with your favorie ones.

Note that the Balance command and double-clicking parentheses/brackets are
complementary - each balance a block of text enclosed by a bracket pair. Balance
always includes the bracket characters in the balanced selection, double-clicking
does not.

Clipboard handling
------------------

Besides standard clipboard handling Eddie supports multiple clipboards
and stack mode for each clipboard.

The main clipboard uses standard shortcuts for the basic copy/paste
functionality:

Cmd-C	Copy
Cmd-X	Cut
Cmd-V	Paste

In addition, there is a swap-paste feature - the contents of the clipboard
and the contents of the selection are interchanged.

Cmd-Ctrl-V	Swap paste

A clipboard can also be used in stack mode - this allows a single clipboard to
hold multiple clipboard items at the same time. By using a stack mode copy or
paste, the text being copied is pushed onto the clipboard, on top of the
existing items. Stack mode copy pops the topmost item from the clipboard stack
and pastes it into a document. If there is any clipboard element left on the
clipboard stack, it will be used in the next paste.
Stack mode and regular mode copy/cut/paste commands can be used interchangeably.

Cmd-Opt-C	Copy and Push onto clipboard stack
Cmd-Opt-X	Cut and Push onto clipboard stack
Cmd-Opt-V	Pop from clipboard stack and Paste

Using the stack mode of a clipboard makes it easy to copy two or more portions
of text in one part of the document and paste them into another. If a clipboard
has more than one clipboard element in it's stack, the element on the top of the
stack can be pasted multiple times by using a regular paste instead of the one-time
pop and paste.

Currently Eddie supports three independent clipboards. Each clipboard is represented
by a clipboard button in the button bar. The first clipboard on the left is the
main clipboard that. The topmost element on the stack of this clipboard is the
standard Be clipboard, shared among applications.

The second and third clipboard have the following keyboard shortcuts assigned

Keypad 1			Paste from second clipboard
Keypad 2			Paste from third clipboard
Cmd-Keypad 1		Copy to second clipboard
Cmd-Keypad 2		Copy to third clipboard
Opt-Keypad 1		Pop from second clipboard stack and Paste
Opt-Keypad 2		Pop from third clipboard stack and Paste
Cmd-Opt-Keypad 1	Copy and Push onto second clipboard stack
Cmd-Opt-Keypad 2	Copy and Push onto third clipboard stack

You can examine the contents of a clipboard by pressing down on the clipboard
button. If there is more than one element in a clibpoard stack, it will be displayed
in a separate panel in the clipboard contents display. The element that will be
pasted next is at the bottom.

Other clipboard button features:

Click			Paste
Opt-Click		Pop from clipboard stack and Paste
Cmd-Click		Copy
Cmd-Opt-Click	Copy and Push onto clipboard stack
Ctrl-Click		Make clipboard empty


Drag&Drop
---------

Besides standard text drag&drop, invoked by clicking the right mouse button in
a selection there are three specialized drag&drop functions:

drop a file				- in shell mode pastes a full path into the current 
						  selection
option-drop a file		- opens the file in a separate window
option-drop a directory	- opens the file panel displaying the directory


Shell mode
----------

A window can be set to shell mode using the Settings menu. In shell mode shell
commands can be executed just as in a terminal shell. Unlike a shell one can
store in the document and reuse them - a convenient alternative to having a
shell history.
There is an actual bash shell running in each shell window. You can use make,
cd, ls, grep, etc. You may set shell variables, aliases and other shell state.
In addition Eddie defines some builtin shell commands.
Editing still works the way it does in other document windows, except for:

Return		- executes a selection or an entire line as a shell script
Ctrl-Return	- acts as Return in a normal window - it just inserts a new line.
			  This is usefull when you do not wan't to execute the line you
			  just typed in
Ctrl-C		- sends a break signal to the shell, stopping makes, etc.
Tab			- completes a path; repeated use will bring up a popup panel
			  with suggested completions
Ctrl-Tab	- inserts a tab character

As with most other keyboard shortcuts, all of the above can be remapped. You may
for instance prefer the more MPW-like mapping of Enter to act as na execute
command and Return to just insert a newline. You may do this by customizing your
UserStartup file with the SetKey commands described later in this document.

Shell prompts appear in the status rectangle in the button bar. If the shell is
executing, a prompt will be light blue. Prompts other than those generated by
the shell are red. Typically ftp, prompt from terminal based tools and scripts,
etc. will display their prompts in red.
Note that the shell does not support terminal escape sequences. It is therefore
not possible to run tools like vi and more. Hopefully the editor text editing
capabilities will offset for this deficiency.


Shell commands
--------------

Type in the shell window and execute as if they were bash shell commands

File <filename>	[-shell]
				- opens a file specified by a full path; if -shell
			  	  specified document will be opened as a shell
Line <lineNumber>	- selects the specified line number
Windows [-o]	- prints the paths of all the open windows; using the -o 
			  	  option causes File to be prepended to each line - this 
			  	  let's one reopen all the files by selecting and executing 
			  	  the list
SetKey			- with no arguments lists all the keyboard bindings you can
			  	  conveniently display all the keyboard shortcuts by 
			 	  executing SetKey in a shell window
SetKey modifiers-key <primitiveFunction>
				- binds the specified key-modifier combo with a primitive 
			  	  function (see list at end of this document for a list of
				  special key names)
UnsetKey modifiers-key
				- removes a modifier-key combo binding
DumpAllMaps		- lists all keyboard bindings in all the available maps
EditKeymap		- Eddie may have multiple keyboard maps. EditKeymap without
			  	 arguments displays all the maps
EditKeymap <mapName>
				- following SetKey calls will have effect on the specified 
			  	  map

Primitives [-nowrap]
				- lists all the primitive functions in Eddie with a short
			  	  description. Note that not all keyboard primitives are 
			  	  actually attached to a keyboard shortcut, you may define 
			  	  keyboard shortcuts using your favorite ones. See the 
			  	  description of the UserStartup file. By default the output
				  of the Primitives command is formatted into a 90 character
				  column. You may use the -nowrap feature when piping the output
				  through grep, etc. when searching for specific commands,
				  for example Primitives -nowrap | grep Paste.

Shell Profile files
-------------------

When opening a shell window or switching a normal text window into a shell window
the bash shell that is initialized by the shell window will read (source) the
/etc/profile and ~/.profile files the same way opening a new Terminal window does.
You may turn this off in the Application Settings - Shell Windows if you need to.
The bash shell sources the ~/.eddieShellProfile file, if there is one. This profile
file is usefull for setting up the shell with settings/commands specific to Eddie
that you don't wan't in your shell if you just open it in a Terminal window.
If the shell window is a Worksheet (see below), ~/.eddieWorksheetProfile profile
file is also sourced, if there is one. The sequence is always :

[/etc/profile, ~/.profile], [~/.eddieShellProfile], [~/.eddieWorksheetProfile]

Note that any output from /etc/profile and ~/.profile is discarded - profile files
usually print out something enlightening during startup and while it is fun and
often even usefull to have it do so in a normal Terminal, in a worksheet style
Eddie shell window you would get a lot of whell window polution that way.
Output from ~/.eddieShellProfile and ~/.eddieWorksheetProfile however is
fully echoed to your shell window. 

Shell tips
----------

- It is convenient set up your bash prompt in your .profile to display the current
directory - making it appear in the Status bar rectangle.
You may do this by adding the following line to ~/.profile :

PS1="\$PWD"": "

If you want to do it right now, place the cursor anywhere on ~/.profile and
hit Cmd-D (Open Selection). Your profile file should open, if you have one. Copy
and paste the line configuring your bash prompt from above. You may now either
restart Eddie or execute the following in your Worksheet window:

. ~/.profile

- To get rid of output from say a compile, you can conveniently use the Undo feature.

- If you select a portion of a line and hit Return, only the selected text will be 
used as a shell commands, the rest will be ignored. If you position the cursor 
anywhere in a line and hit Return, the entire line is executed, including text on 
the line after the cursor.

- When fixing syntax errors during a compile, select an entire line containing
the location of an error, emitted by the Metrowerks compiler, for example select:

File "${EDDIE_HOME}"/'Release notes'; Line 10

and hit Return (to try this in this document, you must first turn on the shell
mode in the Settings menu or by clicking the second rectangle from the left next
to the staus bar; alternatively, copy the line into the Worksheet and
execute it there). Eddie will open the file with the error and select the
appropriate line. Note that this is implemented using a shell script, if instead of
a full path you use say a shell variable (as in our example) and a partial path,
you will get the same result.

- Tab completion combined with the Command-D open selection feature is a very easy
way of opening files - just type/tab-complete the file name with an optional path
and then place the cursor anywhere in the path string, including at the end of
it press Command-D to open it.

- Eddie expects /bin/sh to be bash version 1.14.4 (the one that ships with BeOS).
Bash 2.0 is currently not supported due to annoying incompatibilities with 1.14.4
but will be supported in future versions. If you prefer to use bash 2.0, let me know,
and I'll add support for it sooner.

- You may turn any window into a shell window quickly by clicking the empty
shell icon rectangle in the button bar (rectangle next to the dirty/read only
icon). This may be usefull if you want to use a shell command in a document
but don't want to switch to the worksheet. After you are done with the shell
command, switch back to text editing only mode by clicking the shell icon
again.

- Treating of the different profile files is explained above. In addition to the
already described techniques, you may also use the following trick to configure
bash in a special Eddie specific way:
Before sourcing the ~/.profile, Eddie exports a variable $EDDIE, containing the
path of the application. In the ~/.profile file you may test the value of this
variable - if it is empty, you are executing bash in a Terminal window, if it
contains a string, you are in Eddie. You may execute different parts of an if
statement based on that.

Worksheet
---------

Worksheet is a special window, that comes up in shell mode by default. It is a
document located either in the ~/config/settings/Eddie/ directory or in the
same directory as the Eddie binary. You may choose one of the two to serve as the
Worksheet source directory in Application Settings / Shell Windows. A Worksheet
is automatically saved by default when Eddie quits. When you execute the CloseAll
command (Command-Option-W), the Worksheet stays open.
If you close the worksheet, you may reopen it by pressing Command-0. Usually the
worksheet will be the main and only shell window you will use in Eddie, even though
you can have as many shell windows open as you like (file descriptors, tty's etc.
limitting).

Worksheet tips
--------------

Keep your frequently used commands in your worksheet. Since the worksheet gets saved
automatically, your commands will be available next time you open Eddie. This is
a more persistent and manageable form of a shell history file.
You may reopen all the files you worked next time you run Eddie - before quitting
Eddie execute:
Windows -o
After starting Eddie, select all the File 'xxx' lines and execute them. This will
reopen all the files you worked on last time you ran Eddie.
Unlike MPW, Eddie currently only allows shell comand execution in shell windows.
However a worksheet is only a Command-0 keypress away which makes it easy to
quickly use shell commands.

UserStartup file
----------------

Keyboard shortcuts are defined in the file UserStartup. Examine the file and edit it
to your preference. It illustrates how to define different keyboard maps. You may
enable Emacs emulation mode at the end of the UserStartup file. Changes to
UserStartup take effect next time you launch Eddie. You may experiment with
different keyboard settings temporarily by issuing the corresponding commands
(SetKey, etc.) in the worksheet.

EditKeymap	- successive SetKey commands will be directed to the specified
			  map
NewKeymap <name> [-explicit|-beeping] [-oneShot] [-mapHint <hintString>]
		- defines a new keymap and makes successive SetKey commands target the
		  new map. If -explicit specified, any undefined keyboard combination
		  will be treated as being bound with a NoOp command (the default
		  behavior is all unboud keyboard combinations are passed on to the text
		  engine. If -beeping specified, every undefined keyboard combination
		  will cause a beep. If -oneShot is specified, the keymap will only be
		  active for one keyboard command, after it the default keyboard will be
		  activated. If -mapHint is specified, when a map becomes active, the
		  specified hint string is displayed in the Status bar. This is usefull
		  for multiple keymap setups, such as the Emacs emulation mode. In Emacs
		  mode, pressing Esc will switch you to the Meta keymap and a "M-" will
		  appear in the Status bar.
			
SetDefaultKeymap <name>
		- Makes a specified keyboard the default keyboard.

SetAlternate1Keymap <name>
SetAlternate2Keymap <name>
SetAlternate3Keymap <name>
SetAlternate4Keymap <name>
		- Makes specified keyboards alternate1 through 4; Alternate keyboards
		  may be activated using a corresponding primitive function.

UserStartup is loaded either from ~/config/settings/Eddie/UserStartup and/or
from the directory the Eddie application is in. You may have your own private
version of ~/config/settings/Eddie/UserStartup with your personal customizing
commands, extending the UserStartup that comes with Eddie. Eddie will read both
files, first the main UserStartup, then your customized
~/config/settings/Eddie/UserStartup. This arrangement is convenient in that you
do not have to re-edit the UserStartup each time you get a new version of Eddie.
Note that you may use the UnsetKey command to undefine keyboard commands in the
main UserStartup that you do not care for.

Eddie saves its settings, edited in the preferences window, etc. in a file
~/config/settings/Eddie/settings. The settings file contains textual commands.
In fact, the same commands may be added by the user into the UserStartup file.
The settings file may be edited exactly the same way a UserStartup file. The only
difference is that a settings file is written when Eddie quits, if you made any
changes to the active settings file, they will get overwritten.

Find Window
-----------

Bring up the Find Window by pressing Command-F

Holding down the shift while clicking the Find button will search backwards.
To navigate between the two edit fields in the Find window use Option-Tab.
Tab is used to insert a tab character into the search or replace strings.

See find related keyboard shortcuts earlier in this document for more information.

QuickFind Window
----------------

(Also known as incremental search)

Bring up the QuickFind Window by pressing Command-Option-F, starting the incremental
search at the top of the document

Bring up the QuickFind Window by pressing Command-Control-F, starting the incremental
search at the current position

As you type in a search text, an instance of the text is interactively found in the
target window. As you type in more characters, the search text becomes more accurate
(this feature is also described as incremental search). Hitting the Next button will
look for the next occurrence of the search string. If you delete the search text
using Backspace the previous, less accurate find match will be selected.

Holding down the shift while clicking the Find button (or while hitting
return) will search backwards.

Command-G		- find next (same as hitting return or Command-S)
Command-Shift-G	- find previous (same as hitting shift return)

Command-S		- find next (same as hitting return or Command-G)
Command-Shift-S	- find previous (same as hitting shift return)


Status bar
----------

The Status bar is a rectangle located in the upper left corner of a window,
right under the menu bar. A pencil icon is shown next to the status bar when a
document needs saving. A lock icon is show when a document is read-only.
A read only document is a document that does not have user write permissions
(you may use ls -a to determine the write permissions of a file).
Unlike other editors, Eddie allows you to edit read only documents, however
you will not be able to save the changes into the original file. You may
however use SaveAs or you may Copy and Paste your changes into other documents.
Also, if you change the read only status by making the document writeable
(say you execute "chmod +w <documentPath>" in the Worksheet or you use the
Execute Command feature by clicking the read-only lock icon), you will be
able to save the changes. This works well with source control and other
mechanisms that use write permissions to prevent accidental overwriting of
a file. No matter what means you use to change the write permissions, the
lock icon will dissappear and be replaced by a pencil if you made any changes
and the document can be saved.

If a window belongs to a shell, such as the Worksheet, a shell icon is displayed
next to the status bar. You may click on it to turn the shell window back into
a regular text-only window or you may turn it into a shell window by clicking the
same rectangle. Depending on whether the window is a normal text document or
a shell window, the status bar will either display the line extent of the
selection or the current shell prompt. It is usefull to set up your shell
(by editing the ~/.profile) to display the current pwd as a prompt (see Shell
tips above).
Note that shell window Status bars are somewhat wider to accomodate more
information.


Execute Command Dialog
----------------------

Execute Command Dialog lets you easily run common commands on open documents.
It can for instance be used to quickly change a readonly document to writable
by selecting a chmod +w command in the dialog or to check out a file from a
source code control system using the respective checkout command.
To bring up the Execute Command Dialog click the dirty/read-only icon in the
status bar. You may then select the desired command from the list in the dialog
and execute it by double clicking or hitting OK. If the Use Worksheet checkbox
is selected the command will be executed in the worksheet shell by pasting
it into the worksheet. Unless Append To End Of Worksheet is selected the command
will be pasted into the current selection. If Paste Only is selected the command
will not be executed, you may for instance want to edit it first before executing
it yourself. Executing commands in a worksheet has the advantage that the command
may rely on the current state of the worksheet environment, something that may be
important when for instance when executing source control commands. You may
also reuse the command later by selecting an executing it directly from the
worksheet. For simple commands it may be more convenient to have the command
executed directly. A good example is chmod +w <document name> or chmod -w
<document name> to toggle a read-only state of a document on and off. In this
case you do not need to rely on any environment variables and don't necessarily
want to polute your worksheet with the extra text. By turning off the Use Worksheet
checkbox the command will be executed in a temporary shell that quits immediately
after the command.

Currently Execute Command Dialog needs to be configured by adding commands in
the UserStartup. The syntax is:

AddToExecuteDialog '<someCommand> $DOCUMENT' [-worksheet] [-appendToEnd] [-pasteOnly]

The command string needs to be in quotes. The $DOCUMENT variable gets replaced
by the name of the document you execute the command on. The three different
options correspond to the three checkboxes.

Here are some example entries:

# a command to check out a file, needs to be issued in a worksheet because
# it relies on the source code control environment being set up
AddToExecuteDialog 'cho $DOCUMENT' -worksheet -appendToEnd

# a command to paste a open command into the worksheet; You will have to
# execute it later yourself because of the -pasteOnly option
AddToExecuteDialog 'File $DOCUMENT' -worksheet -appendToEnd -pasteOnly

# a commad to set a document to be read-only; executes directly without
# pasting anything into the worksheet
AddToExecuteDialog 'chmod -w $DOCUMENT'
 


-------------------------------------------------------------------------------------

Plugins
-------


Many editor features are handled by plugins and will do so even more in the future
releases. A plugin API is available for developers interrested in writing Eddie
plugins. C/C++ syntax coloring is implemented as a plugin. Plugins may or may not
have a corresponding button in the button bar. Tool tips are available for plugin
buttons, move the mouse cursor over a button and leave it there for about a second.

Syntax Coloring
---------------

Automatically colors text in C, C++, assembly and makefile documents (more to come).
Colors may be modified in the Application Settings.

Function popup
--------------
- button with two blue curly braces

Pressing down on this button will bring up a popup menu with all the funcitons in the
document. The function located near the current cursor position is marked. Selecting
an item in the menu brings you to the respective function. If a function is
overloaded the parameters are also shown so that the different function signatures
can be recognized.

When you press the button:
Hold down Option to sort the menu
Hold down Shift to include structs
Hold down Control to show class members (usefull in header files with large classes)
Hold down Control and Shift to show everything but function definitions

The Function popup button is split up into two halves. Click on the top half to
find the previous function. Click on the bottom half to find the next function.

Magic Prototyper
----------------
- button with a magic wand and a red triangle

Makes writing class definitions and corresponding declarations a snap.

Prototyper Features:

Clicking or Pressing on an empty prototyper button will load the prototyper with
prototypes of selected C/C++ code.

Pressing on a full prototyper button displays the prototypes in a popup window.

Clicking on a full prototyper button pastes the prototypes into the current selection

Control-clicking on a full prototyper button empties the prototyper.

Holding down option while loading the prototyper makes it generate prototypes for
everything (including static functions, pure virtual functions, etc.).

Holding down shift while loading will append new prototypes to prototyper clipboard

The prototyper remains empty if selected code cannot be prototyped.

C functions -
Selecting non-static C function definition will result in generating corresponding
function declarations with extern prefixes. Holding down the shift includes
prototypes for static functions. Selecting a C function declarations generates an
inverse prototype - an empty version of the function with empty curly braces for you
to fill out with code.

C++ functions -
Selecting C++ functions and clicking the prototyper will generate respective member
function definitions, formated such, that they can be immediately pasted into a
corresponding class.

C++ class - inverse prototyping
Selecting a C++ class definition and clicking the prototyper button will generate
corresponding empty functions. If the class definition contains inline code, the
inline code is included. Holding down shift also includes prototypes for pure virtual
functions and functions that are inlined in the class definition.

The prototyper exports several primitive functions that can be assigned a keyboard
shorcut by using SetKey. Use the Primitives command in the worksheet to list all
the available primitive functions or execute 

Primitives -nowrap | grep Prototyper 

in the Worksheet.

By default the following two funcitons are assigned keyboard shortcuts (more are left
unassigned).
 
Control-Option-P	- if empty, gets prototypes, if full pastes them into selection
Control-P			- if empty, gets all prototypes, if full pastes them into selection
					  (all meaning pure virtual, inlined and static functions are
					  included)

Ifdef balancer
--------------
- button with the

	#if
	#el 

text

Invoked by Command-double clicking on a line containing an #if, #ifdef, #ifndef,
#else or #endif. Shift controls including #ifdef/#endif lines in the selection. When
clicking on else, use Option to select the #else-#endif portion of the #ifdef. Click
the button to select the #ifdef block enclosing the current selection. Keep clicking
to expand to the next ifdef level.

By pressing the Ifdef balancer button you can access the menu that allows #ifdefing
out selected lines of text. #if 0 and #ifdef DEBUG are preconfigured, the first menu
item is used to #ifdef with a user defined symbol - to define a symbol select the
any text in a document and invoke the "Use as ifdef symbol" menu item - the selected
text will become the user defined ifdef symbol.

The ifdef balancer exports several primitive functions that can be assigned a keyboard
shorcut by using SetKey. See the list of primitives at the end of this document or
execute

Primitives -nowrap | grep IfdefBalancer 

in the Worksheet to see them all.

-------------------------------------------------------------------------------------

The tellEddie command line tool
-------------------------------

tellEddie is used to pipe built-in commands (such as SetKey, Primitives, etc.) from
a Worksheet or a shell window back into Eddie for execution. It ensures shell variables
are properly expanded and evaluated making the builtin shell commands well integrated
with the rest of the original bash commands and makes them behave identically.

In addition to that tellEddie can be used to open a document in a running copy of Eddie
and block the command line until the window corresponding to the open document gets
closed. This feature is usefull with some source control systems such as RCS for
writing checkin notes, etc. Usually systems like this are preconfigured with the
editor of your choice (which could be Eddie in your case). During checkin the editor
gets launched from the command line you invoked the checkin command from, you type
up your chekin notes and close the editor which makes the checkin proceed with checking
in files. If you are already running Eddie (you may be executing the checkin commands
from your Worksheet), this will not work because Eddie is already running and the
launch eddie command will return immediately without the checkin notes being typed up.
To prevent this, you may use the blocking feature of tellEddie. Configure your source
control environment to list:

export EDITOR='tellEddie -w'

or a corresponding command, depending on the syntax. The -w option used with tellEddie
will cause the file opened as a result to block the command line that invoked it
untill the corresponding window is closed.
For this to work you will also need to include a symbolic link to tellEddie from
~/config/bin or you may specify a full path to the tellEddie tool in the export command.

-------------------------------------------------------------------------------------

Appendix A

Names of special keys used SetKey

Modifiers Mac

	Shift
	Command
	Control
	Caps
	ScrollLock
	NumLock
	Option
	Menu
	LeftShift
	RightShift
	LeftCommand
	RightCommand
	LeftControl
	RightControl
	LeftOption
	RightOption

Modifiers PC

	Shift
	Alt
	Control
	Caps
	ScrollLock
	NumLock
	Win
	Menu
	LeftShift
	RightShift
	LeftCommand
	RightCommand
	LeftControl
	RightControl
	LeftWin
	RightWin

The Mac and PC modifier names are interchangeable, you may use the PC names
on a Mac and vice-versa. This is to allow sharing the same UserStartup on both
platforms.

The left/right flavors of the various modifiers bind a keyboard shortcut to that
specific modifier only (for instance SetKey RightShift-A will have no affect when
pressing A with the left shift key down). The modifier names without the left/right
flavor specification work with either of the modifier pair.

Special key names
	Backspace	- disguised as Delete on some Mac keyboards
	Return
	Space
	Tab
	Escape
	LeftArrow
	RightArrow
	UpArrow
	DownArrow
	Insert		- Ins/Help on Mac keyboards
	Delete		- Del on Mac keyboards
	Home
	End
	PageUp
	PageDown
	F1			- function key 1
	F2			- etc.
	F3
	F4
	F5
	F6
	F7
	F8
	F9
	F10
	F11
	F12
	PrintScreen
	ScrollLock
	Pause

Alternate special key names (numerical keypad)
	Kp0			- numerical keypad 0
	Kp1			- etc.
	Kp2
	Kp3
	Kp4
	Kp5
	Kp6
	Kp7
	Kp8
	Kp9
	Enter		- Enter at the very right-bottom corner of the keyboard
	KpDel		- numerical keypad Del/. 
	Kp+			- numerical keypad +
	Kp-			- numerical keypad -

If any of the alternate numerical keypad key names is used in a SetKey command,
that command will be independent of the corresponding keyboard shortcut on the
main keyboard. For instance mapping

SetKey Option-Enter Beep 

will cause a beep when pressing the Enter key with an Option (Windows) key but not
when pressing Return and Option. If unassigned however, pressing a keyboard combination
shortcut using Enter will do the same as the equivalent shortcut with Return.
(Note that some keyboards have two Enter keys, you will have to make a mental
transformation and think of the one to the right of the main keyboard area as Return).

-------------------------------------------------------------------------------------

Appendix B

The following is a list of all the primitive functions that can be used by SetKey.
This list gets printed out when you invoke the Primitives command in a shell
window. As described in the SetKey command description, these primitives can
be bound to keyboard shortcuts in the UserStartup file. Note that many of the
primitive calls overlap in their functionality (for example OpenSelection,
SimpleOpenSelection, TraditionalOpenSelection, OpenHeader) and have only
subtle differences. This is to provide a maximal level of customization.
Also note that some editor primitives are defined by plugins. This allows
seamless integration of plugin features into the editor.

Primitives
# ActivateAlternate1Map              - Switch the active keyboard map to the alternate1 map 
# ActivateAlternate2Map              - Switch the active keyboard map to the alternate2 map 
# ActivateAlternate3Map              - Switch the active keyboard map to the alternate3 map 
# ActivateAlternate4Map              - Switch the active keyboard map to the alternate4 map 
# ActivateAlternate5Map              - Switch the active keyboard map to the alternate5 map 
# ActivateDefaultMap                 - Switch the active keyboard map to the default map 
# ActivateNextWindow                 - Rotate windows, bringing the next window to the front 
# ActivatePreviousWindow             - Rotate windows, bringing the previous window to the 
#                                      front 
# ActivateWorksheet                  - Make Worksheet the active document; if Worksheet not 
#                                      open, try opening it 
# Backspace                          - Delete selected text or character after cursor 
# Balance                            - Extend selection to enclosing (), [] or {} pair 
# Beep                               - Beep 
# CapitalizeWord                     - Convert first character of a word to upper case and 
#                                      move selection to word end 
# Clear                              - Delete selected text 
# ClearClipboard                     - Remove everything from the main clipboard 
# ClearClipboardExtended1            - Remove everything from the first extended clipboard 
# ClearClipboardExtended2            - Remove everything from the second extended clipboard 
# Close                              - Close window 
# CloseAll                           - Close all documents, leave worksheet open 
# Copy                               - Copy selected text into main clipboard 
# CopyAndAppend                      - Append selected text to the main clipboard contents 
# CopyAndAppendExtended1             - Append selected text to the first extended clipboard 
#                                      contents 
# CopyAndAppendExtended2             - Append selected text to the second extended clipboard 
#                                      contents 
# CopyExtended1                      - Copy selected text into first extended clipboard 
# CopyExtended2                      - Copy selected text into second extended clipboard 
# CopyOnStack                        - Copy selected text as a new entry onto the clipboard 
#                                      stack of the main clipboard 
# CopyOnStackExtended1               - Copy selected text as a new entry onto the clipboard 
#                                      stack of the first extended clipboard 
# CopyOnStackExtended2               - Copy selected text as a new entry onto the clipboard 
#                                      stack of the second extended clipboard 
# Cut                                - Cut selected text into main clibpoard 
# CutAndAppend                       - Cut selected text and append to the main clipboard 
# CutAndAppendExtended1              - Cut selected text and append to the first extended 
#                                      clipboard 
# CutAndAppendExtended2              - Cut selected text and append to the main clipboard 
# CutExtended1                       - Cut selected text into first extended clipboard 
# CutExtended2                       - Cut selected text into second extended clipboard 
# CutOnStack                         - Cut selected text as a new entry onto the clipboard 
#                                      stack of the main clipboard 
# CutOnStackExtended1                - Cut selected text as a new entry onto the clipboard 
#                                      stack of the first extended clipboard 
# CutOnStackExtended2                - Cut selected text as a new entry onto the clipboard 
#                                      stack of the second extended clipboard 
# Delete                             - Delete selected text or character before cursor 
# DeleteFromDocumentBeginning        - Delete text from beginning of document to selection 
#                                      end 
# DeleteFromLineBeginning            - Delete text from beginning of line to selection end 
# DeleteFromWordBeginning            - Delete text from beginning of word to selection end 
# DeleteLine                         - Extend selection to a whole line/lines and delete 
# DeleteToDocumentEnd                - Delete text from selection start to document end 
# DeleteToLineEnd                    - Delete text from selection start to line end 
# DeleteToWordEnd                    - Delete text from selection start to word end 
# DeleteWord                         - Extend selection to a whole word/words and delete 
# DownArrow                          - Move cursor to the next line 
# EmacsKillToLineEnd                 - Emacs style kill line - delete text from selection 
#                                      start to line end and place into kill buffer 
# EmacsKillToWordEnd                 - Emacs style kill word - delete text from selection 
#                                      start to word end and place into kill buffer 
# EmacsYank                          - Emacs style yank - paste kill buffer into selection 
# EmacsYankPop                       - Emacs style yank pop - pop the top item in the kill 
#                                      buffer, making the next item available 
# EnterAndFind                       - Enter selection as a search string and search for it 
#                                      forward 
# EnterAndFindReverse                - Enter selection as a search string and search for it 
#                                      backward 
# EnterFindString                    - Enter selection as a search string 
# ExtendLeft                         - Extend selection one character left 
# ExtendRight                        - Extend selection one character right 
# ExtendToDocumentBeginning          - Extend selection to document beginning 
# ExtendToDocumentEnd                - Extend selection to document end 
# ExtendToLine                       - Extend selection the beginning/end of the enclosed 
#                                      line/lines 
# ExtendToLineBeginning              - Extend selection start the beginning of the first 
#                                      selected line 
# ExtendToLineEnd                    - Extend selection end the end of the last selected line 
# ExtendToSubword                    - Extend selection the beginning/end of the enclosed 
#                                      subword/words 
# ExtendToSubwordBeginning           - Extend selection the beginning of the enclosed 
#                                      subword/words 
# ExtendToSubwordEnd                 - Extend selection the end of the enclosed subword/words 
# ExtendToWord                       - Extend selection the beginning/end of the enclosed 
#                                      word/words 
# ExtendToWordBeginning              - Extend selection start the beginning of the first 
#                                      selected word 
# ExtendToWordEnd                    - Extend selection end the end of the last selected word 
# FindAgain                          - Find the next occurrence of the current search string 
# GoToEnd                            - Move cursor to document end 
# GoToHome                           - Move cursor to document start 
# GoToLine                           - Show the Go to line dialog 
# GoToPageDown                       - Move cursor to the bottom of the page or one page down 
# GoToPageUp                         - Move cursor to the top of the page or one page up 
# IfdefBalancerBalance               - Extend selection to enclosing ifdef/endif pair 
# IfdefBalancerIfDebugSelection      - Enclose selected lines with an #if DEBUG/#endif pair 
# IfdefBalancerIfUserSymbolSelection - Enclose selected lines with an #if 
#                                      <USER_SYMBOL>/#endif pair; <USER_SYMBOL> is defined by 
#                                      selecting a desired string and using the Use 
#                                      selection... menu item 
# IfdefBalancerIfZeroSelection       - Enclose selected lines with an #if 0/#endif pair 
# IfdefBalancerInclusiveBalance      - Extend selection to enclosing ifdef/endif pair, 
#                                      inclusive 
# IndentLeft                         - Remove the first tab on each selected line 
# IndentRight                        - Add a tab at the start of each selected line 
# LeftArrow                          - Move cursor left 
# LowerCaseSelection                 - Convert selection to lower case 
# LowerCaseWord                      - Select word and convert to lower case 
# NewDocument                        - Create a new empty document 
# NoOp                               - Do absolutely nothing 
# OpenAfter                          - Insert a line before the current line and move the 
#                                      cursor to the new line 
# OpenBefore                         - Insert a line after the current line and move the 
#                                      cursor to the new line 
# OpenDocument                       - Show the Open document panel in previously accessed 
#                                      directory 
# OpenFindPanel                      - Show the Find panel 
# OpenFromDocumentsDir               - Show the Open document panel in curent documents 
#                                      directory 
# OpenHeader                         - Show the Open header dialog 
# OpenLine                           - Emacs style OpenLine: Insert a newline after selection 
#                                      start 
# OpenQuickFindPanel                 - Show the QuickFind panel 
# OpenQuickFindPanelFromCurrentPos   - Show the QuickFind panel, starting search at current 
#                                      position 
# OpenSelection                      - Extend selection to a file name and try opening the 
#                                      selected file name 
# Paste                              - Paste the main clipboard into the selection 
# PasteExtended1                     - Paste the first extended clipboard into the selection 
# PasteExtended2                     - Paste the second extended clipboard into the selection 
# PasteFromStack                     - Pop the contents of the main clipboard and paste it 
#                                      into the selection; the next item on the clipboard 
#                                      stack will become available 
# PasteFromStackExtended1            - Pop the contents of the first extended clipboard and 
#                                      paste it into the selection; the next item on the 
#                                      clipboard stack will become available 
# PasteFromStackExtended2            - Pop the contents of the second extended clipboard and 
#                                      paste it into the selection; the next item on the 
#                                      clipboard stack will become available 
# PopClipboard                       - Pop the top item from the main clipboard; the next 
#                                      item on the clipboard stack will become available 
# PopClipboardExtended1              - Pop the top item from the first extended clipboard; 
#                                      the next item on the clipboard stack will become 
#                                      available 
# PopClipboardExtended2              - Pop the top item from the second extended clipboard; 
#                                      the next item on the clipboard stack will become 
#                                      available 
# PrototyperAppendAllPrototypes      - Add prototypes from selection to prototyper clipboard; 
#                                      include static, inlined and pure virtual calls 
# PrototyperAppendPrototypes         - Add prototypes from selection to prototyper clipboard 
# PrototyperClearPrototypes          - Clear prototyper clipboard 
# PrototyperGetAllPrototypes         - Fill prototyper clipboard with prototypes from 
#                                      selection; include static, inlined and pure virtual 
#                                      calls 
# PrototyperGetOrPasteAllPrototypes  - If empty, fill clipboard, include static, inlined and 
#                                      pure virtual calls, if full, paste prototyper 
#                                      clipboard into selection 
# PrototyperGetOrPastePrototypes     - If empty, fill clipboard, if full, paste prototyper 
#                                      clipboard into selection 
# PrototyperGetPrototypes            - Fill prototyper clipboard with prototypes from 
#                                      selection 
# PrototyperPastePrototypes          - Paste prototyper clipboard into selection 
# QuickFindFromStart                 - Find string in quick find panel from begining of 
#                                      document 
# QuickFindNext                      - Find string in quick find panel from current selection 
# QuickFindPrevious                  - Find string reverse in quick find panel from current 
#                                      selection 
# Quit                               - Quit Eddie, prompting to save unsaved documents 
# Redo                               - Undo the effect of a previous Undo, if applicable 
# ReplaceAll                         - Replace all occurrences of the search string with a 
#                                      replacement text from current position to the document 
#                                      end 
# ReplaceAndFind                     - Replace selection with replace text and find next 
#                                      occurrence of the current search string 
# ReverseFindAgain                   - Find the previous occurrence of the current search 
#                                      string 
# Revert                             - Replace the document contens with the contents last 
#                                      saved to the disk 
# RightArrow                         - Move cursor right 
# Save                               - Save document 
# SaveAll                            - Save all documents 
# SaveAs                             - Open the Save as panel 
# SelectAll                          - Extend selection from document start to document end 
# SelectLineBeginning                - Move cursor to the beginning of the first selected 
#                                      line 
# SelectLineEnd                      - Move cursor to the end of the last selected line 
# SelectSubwordBeginning             - Move cursor to the beginning of the first selected 
#                                      subword 
# SelectSubwordEnd                   - Move cursor to the end of the last selected subword 
# SelectWordBeginning                - Move cursor to the beginning of the first selected 
#                                      word 
# SelectWordEnd                      - Move cursor to the end of the last selected word 
# ShellBreak                         - Break the process currently executing in the shell 
#                                      (Ctrl-C) 
# ShellExecute                       - Execute selection or a line with the cursor in the 
#                                      shell 
# ShellInsertReturn                  - Insert a newline character (in shell windows you may 
#                                      prefer to not have this as a default of hitting the 
#                                      Return key) 
# ShellInsertTab                     - Insert a tab character (in shell windows you may 
#                                      prefer to not have this as a default of hitting the 
#                                      Tab key) 
# ShellTabComplete                   - Try completing a file path in the shell 
# ShowEnd                            - Scroll document to the bottom, do not move 
#                                      cursor/selection 
# ShowHome                           - Scroll document to the top, do not move 
#                                      cursor/selection 
# ShowPageDown                       - Scroll document one page down, do not move 
#                                      cursor/selection 
# ShowPageUp                         - Scroll document one page up, do not move 
#                                      cursor/selection 
# SimpleOpenSelection                - Try opening the selected file name without first 
#                                      extending the selection 
# SplitPaneHorizontal                - Split the window or the focused pane horizontaly 
# SplitPaneVertical                  - Split the window or the focused pane verticaly 
# SwapWithClipboard                  - Swap the contents of the selection with the contents 
#                                      of the main clipboard 
# SwapWithClipboardExtended1         - Swap the contents of the selection with the contents 
#                                      of the first extended clipboard 
# SwapWithClipboardExtended2         - Swap the contents of the selection with the contents 
#                                      of the second extended clipboard 
# SwapWithHeaderFile                 - If .cpp file open, try openning a .h file and vice 
#                                      versa 
# SwapWithNextCharacter              - Swap selection with following character 
# SwapWithNextLine                   - Swap the lines containing the selection with the next 
#                                      line (drag lines one down) 
# SwapWithPreviousCharacter          - Swap selection with previous character 
# SwapWithPreviousLine               - Swap the lines containing the selection with the 
#                                      previous line (drag lines one up) 
# SwitchToNextPane                   - Shift focus to the next pane if a window has multiple 
#                                      panes open 
# SwitchToPreviousPane               - Shift focus to the next pane if a window has multiple 
#                                      panes open 
# TraditionalOpenSelection           - If selection empty, run open header panel, else extend 
#                                      selection to a file name and try opening the selected 
#                                      file name 
# Transpose                          - Emacs-style transpose - swap two characters around 
#                                      cursor 
# Undo                               - Undo last action or series of consecutive actions 
# UnsplitPane                        - Unsplits the focused pane if the window is split 
# UpArrow                            - Move cursor to the previous line 
# UpperCaseSelection                 - Convert selection to upper case 
# UpperCaseWord                      - Select word and convert to upper case 

-------------------------------------------------------------------------------------

Legal suff, disclaimers:

This version of Eddie is shareware. You may use it, copy it and redistribute
it freely. It most certainly contains bugs, some of the features are not fully
functional. Use at your own risk, you have been warned.


PAVEL CISLER PROVIDES THIS SOFTWARE "AS IS", WITH NO WARRANTY 
OF ANY KIND EITHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING BUT 
NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT WILL PAVEL CISLER BE LIABLE FOR ANY INDIRECT 
DAMAGES OR OTHER RELIEF ARISING OUT OF YOUR USE OR INABILITY TO 
USE THE PROGRAM INCLUDING, BY WAY OF ILLUSTRATION AND NOT 
LIMITATION, LOST PROFITS, LOST BUSINESS OR LOST OPPORTUNITY, OR 
ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT 
OF SUCH USE OR INABILITY TO USE THE PROGRAM, EVEN IF PAVEL 
CISLER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR 
FOR ANY CLAIM BY ANY OTHER PART.

Be Incorporated is no way responsible for Eddie, Eddie is not a product of
Be Incorporated.

Further disclaimers:

IF FICUS DOESN'T QUIT COMPLAINING ABOUT C++, HE WILL BE FOREVER REVOKED
THE LICENSE TO USE EDDIE, REGARDLESS OF THE HARDWARE PLATFORM, OPERATING SYSTEM
OR JURISDICTION.

-------------------------------------------------------------------------------------

Eddie is built strictly out of ingredients, available to each and every Be developer.
No unpublished APIs or proprietary BeOS code is been called, executed or otherwise
abused in the innards of Eddie source code.

